﻿<%@ Page Language="C#" AutoEventWireup="true" MasterPageFile="~/Components/Components.Master" CodeBehind="ScriptManager.aspx.cs" Inherits="AjaxControlFramework.Docs.Components.ScriptManager" %>
<%@ Register TagPrefix="docs" TagName="DeclarativeExample1" Src="~/Examples/ScriptManager/DeclarativeExample1.ascx" %>
<%@ Register TagPrefix="docs" TagName="InlineExample1" Src="~/Examples/ScriptManager/InlineExample1.ascx" %>
<%@ Register TagPrefix="docs" TagName="EmbeddedExample1" Src="~/Examples/ScriptManager/EmbeddedExample1.ascx" %>
<%@ Register TagPrefix="docs" TagName="ProgrammaticExample1" Src="~/Examples/ScriptManager/ProgrammaticExample1.ascx" %>

<asp:Content runat="server" ContentPlaceHolderID="HeadTitle">
    ScriptManager - Components - Docs - AJAX Control Framework
</asp:Content>

<asp:Content runat="server" ContentPlaceHolderID="Title">
    <span class="underline">ScriptManager</span> (AjaxControlFramework.ScriptManager)
</asp:Content>

<asp:Content runat="server" ContentPlaceHolderID="Overview">
    <p>
        The <span class="code_element">ScriptManager</span> is one of the out-of-the-box UI controls that comes packaged with the <span class="important">AJAX Control Framework</span>. 
        It lets you reference JavaScript files and scripts in embedded resources on any page, any User Control or even programmatically, and the scripts will all be rendered uniformly 
        at the location you specify them. You can tell the scripts you reference in your <span="code_element">ScriptManager</span>ss to load either at the bottom of the &lt;head&gt;, 
        the bottom of the &lt;body&gt; or "here" (right where you declared them). You can have as many <span="code_element">ScriptManager</span>s in your markup as you want and reference the same scripts each time, 
        and the <span="code_element">ScriptManager</span> ensures that there are no duplicates rendered. You can also specify dependencies so that your scripts will always load in the correct order. 
    </p>
    
    <p>
        Read on before you think "this isn't really necessary." The <span class="code_element">ScriptManager</span> complements the coding style and structure of the the 
        <span class="important">AJAX Control Framework</span> <span class="important">VERY</span> well.
    </p>
</asp:Content>

<asp:Content runat="server" ContentPlaceHolderID="Remarks">
    <p>
        I've you've ever called the <span class="code_element">System.Web.UI.ClientScriptManager.RegisterClientScriptResource</span> method 
        then you've probably noticed that ASP.NET puts the &lt;script&gt; reference near the top of the &lt;body&gt; element. The best practice 
        for &lt;script&gt; elements is to declare them at the bottom of the &lt;body&gt; so that their loading doesn't hold up the intialization 
        of the rest of the DOM (this can be noticable if there are ALOT of embedded JavaScript files). Except for maybe a few straggling images, 
        everything a page needs would be loaded by the time a script executes, ensuring any code that requires a DOM element to be present will be 
        able to find it and execute properly. Often times when there are dependencies between script files having certain ones render at the top 
        of the body, beyond your control, causes heartache for the developer. I've experienced this particular heartache many times.
    </p>
    
    <p>
        Now lets say you're developing a module for a Content Management System like <span class="important">DotNetNuke</span>. It's good practice, 
        for the sake of componentization, to declare your &lt;script&gt; elements in whatever Page or User Control it is needed within the scope 
        of your module or plugin. In the case of <span class="important">DotNetNuke</span>, you would declare the scripts your module needs in one 
        of your module's .ascx files rather than in the Default.aspx page of the site. This ensures that the script file doesn't get loaded unless 
        that particular module is on the current page being viewed (if your module uses 4 or 5 different JavaScript files it would be nonsense to
        have all of them load on every page). Once again, this is good practice if you're trying to achieve componentization. But, you may break the 
        best practice of putting all your scripts at the bottom of the page if your components are User Controls. When you include a &lt;script&gt; 
        element in a User Control, the script renders wherever the User Control renders, whether that be in the middle of the page's markup or at the 
        bottom. EVEN WORSE, if the Default.aspx file references the jQuery library just like your module does, then jQuery will be loaded 
        <span class="important">more than once</span>. AHHHHH!!!!
    </p>
    
    <p>
        So it looks like you're gonna have to make a compromise somewhere if you want to avoid load-dependencies, duplicate script declarations and stay 
        strong in the ways of componentization. No thanks. I refuse. I believe it is <span class="important">your</span> duty to refuse to accept such a 
        compromise as well. The <span class="important">AJAX Control Framework</span> comes to our rescue in this case with the 
        <span class="code_element">ScriptManager</span> control. <strong>Here are the 7 major features of the <span class="code_element">ScriptManager</span>, 
        all of which resolve the issues mentioned above:</strong>
    </p>
    
    <ul>
        <li>Declaratively specify where scripts are to be rendered, at the bottom of the &lt;body&gt;, at the bottom of the &lt;head&gt; or exactly where they were declared.</li>
        <li>Maintains a global collection of script references behind-the-scenes, ensuring no duplicate scripts are rendered.</li>
        <li>Sorts script references before they are rendered by dependencies, which are declared via markup or procedural code.</li>
        <li>Allows for programattic additions of references to the manager so that non-visual components (especially custom, controls deriving from WebControl and Control).</li>
        <li>Can be declared any number of times within a single page instance and not incur the "Only one instance of a ScriptManager can be added to the page" exception.</li>
        <li>Doesn't automatically load the <span class="important">ASP.NET AJAX</span> library, just in case you didn't want to use it and still be able to manager and centralize all your script references.</li>
        <li>Doesn't leave a footprint in ViewState (just in case you were worried).</li>
        <li>Allows for inline script blocks.</li>
    </ul>
</asp:Content>
    
<asp:Content runat="server" ContentPlaceHolderID="Examples">
    <docs:DeclarativeExample1 runat="server" />
    <docs:InlineExample1 runat="server" />
    <docs:EmbeddedExample1 runat="server" />
    <docs:ProgrammaticExample1 runat="server" />
</asp:Content>